---
title: Load a document
summary: Materialises a Document's bytes from memory or disk.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
library: PdfAPI.Core
reference_type: package
operation_id: OP-09
trigger: Document.Load(string, bool) / Document.Load(byte[], string) / Document.CreateEmpty(string) / instance Load() invoked
---

# Load a document

This operation covers the static factory and instance methods that construct a `Document` and populate its in-memory bytes from a file path or a byte array.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-09 |
| **Trigger** | Caller invokes `Document.Load(string, bool)`, `Document.Load(byte[], string)`, `Document.CreateEmpty(string)`, or the instance `Load()` |
| **Inputs** | File path and `mustExist` flag, or bytes + extension |
| **Outputs** | A new/loaded `Document`, or `true`/`false` from the instance `Load()` |
| **Primary components** | `PdfAPI.Core.Document.Load`, `Document.CreateEmpty`, instance `Document.Load()` |
| **Entry point** | `PdfAPI.Core\Document.cs` |

## Steps

1. Generate a new `Guid` as the document `Id` (static factories). ([BR-19](../business-rules.md#br-19-new-documents-receive-a-new-guid-identity))
2. For the path overload: read all bytes when the file exists; when it does not exist and `mustExist` is true, throw `Exception` with the missing path; otherwise continue with null bytes. ([BR-20](../business-rules.md#br-20-missing-file-load-behavior))
3. Trim leading dots from the supplied extension and compose `FileName` as `{Id}.{FileExtension}`. ([BR-21](../business-rules.md#br-21-document-file-name-convention))
4. Instance `Load()`: return `true` immediately when bytes are already in memory; otherwise read `FilePath` from disk when it exists and return `true`; return `false` when neither is available. ([BR-05](../business-rules.md#br-05-document-load-requires-in-memory-or-on-disk-bytes))

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start(["Document.Load / CreateEmpty"]) --> Id["Assign new Guid Id"]
	Id --> Path{Path overload?}
	Path -->|Yes| Exists{File exists?}
	Exists -->|Yes| Read["Read all bytes"]
	Exists -->|No| MustExist{mustExist?}
	MustExist -->|Yes| Throw(["Throw Exception:<br>file does not exist"])
	MustExist -->|No| NullBytes["Continue with null bytes"]
	Path -->|No| BytesOverload["Assign supplied bytes"]
	Read --> Name["Trim extension,<br>compose FileName"]
	NullBytes --> Name
	BytesOverload --> Name
	Name --> Done([Return Document])
```

## Failure and edge-case behavior
- Loading from a non-existent path with `mustExist = false` succeeds but leaves `File` null; a subsequent instance `Load()` call on that document returns `false` ([BR-05](../business-rules.md#br-05-document-load-requires-in-memory-or-on-disk-bytes), [BR-20](../business-rules.md#br-20-missing-file-load-behavior)).

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Security and authorization](../security-authorization.md)

## Sources
- `PdfAPI.Core\Document.cs`